/*
 * %W% %E%
 *
 * Copyright (c) 2006, Oracle and/or its affiliates. All rights reserved.
 * ORACLE PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
 */

package java.lang;

import java.io.IOException;

/**
 * An object to which <tt>char</tt> sequences and values can be appended. The
 * <tt>Appendable</tt> interface must be implemented by any class whose
 * instances are intended to receive formatted output from a
 * {@link java.util.Formatter}.
 *
 * <p>
 * The characters to be appended should be valid Unicode characters as described
 * in <a href="Character.html#unicode">Unicode Character Representation</a>.
 * Note that supplementary characters may be composed of multiple 16-bit
 * <tt>char</tt> values.
 *
 * <p>
 * Appendables are not necessarily safe for multithreaded access. Thread safety
 * is the responsibility of classes that extend and implement this interface.
 *
 * <p>
 * Since this interface may be implemented by existing classes with different
 * styles of error handling there is no guarantee that errors will be propagated
 * to the invoker.
 *
 * @version %I%, %G%
 * @since 1.5
 */

//http://tool.oschina.net/uploads/apidocs/jdk-zh/java/lang/Appendable.html
//能够被添加 char 序列和值的对象
/*
 * 三个append实现
 * append(char c)
 * append(CharSequence csq) 
 * append(CharSequence csq, int start, int end)
 * 
 * 返回类型都是Appendable
 * 
 * 官方文档：如果某个类的实例打算接收取自 Formatter 的格式化输出，那么该类必须实现 Appendable 接口。
 * Formatter.out返回类型为Appendable
 * 	Appendable out()  返回输出的目标文件。
 * 
 */
public interface Appendable {

	/**
	 * Appends the specified character sequence to this <tt>Appendable</tt>.
	 *
	 * <p>
	 * Depending on which class implements the character sequence <tt>csq</tt>,
	 * the entire sequence may not be appended. For instance, if <tt>csq</tt> is
	 * a {@link java.nio.CharBuffer} then the subsequence to append is defined
	 * by the buffer's position and limit.
	 *
	 * @param csq
	 *            The character sequence to append. If <tt>csq</tt> is
	 *            <tt>null</tt>, then the four characters <tt>"null"</tt> are
	 *            appended to this Appendable.
	 *
	 * @return A reference to this <tt>Appendable</tt>
	 *
	 * @throws IOException
	 *             If an I/O error occurs
	 */
	Appendable append(CharSequence csq) throws IOException;

	/**
	 * Appends a subsequence of the specified character sequence to this
	 * <tt>Appendable</tt>.
	 *
	 * <p>
	 * An invocation of this method of the form <tt>out.append(csq, start,
	 * end)</tt> when <tt>csq</tt> is not <tt>null</tt>, behaves in exactly the
	 * same way as the invocation
	 *
	 * <pre>
	 * out.append(csq.subSequence(start, end))
	 * </pre>
	 *
	 * @param csq
	 *            The character sequence from which a subsequence will be
	 *            appended. If <tt>csq</tt> is <tt>null</tt>, then characters
	 *            will be appended as if <tt>csq</tt> contained the four
	 *            characters <tt>"null"</tt>.
	 *
	 * @param start
	 *            The index of the first character in the subsequence
	 *
	 * @param end
	 *            The index of the character following the last character in the
	 *            subsequence
	 *
	 * @return A reference to this <tt>Appendable</tt>
	 *
	 * @throws IndexOutOfBoundsException
	 *             If <tt>start</tt> or <tt>end</tt> are negative,
	 *             <tt>start</tt> is greater than <tt>end</tt>, or <tt>end</tt>
	 *             is greater than <tt>csq.length()</tt>
	 *
	 * @throws IOException
	 *             If an I/O error occurs
	 */
	Appendable append(CharSequence csq, int start, int end) throws IOException;

	/**
	 * Appends the specified character to this <tt>Appendable</tt>.
	 *
	 * @param c
	 *            The character to append
	 *
	 * @return A reference to this <tt>Appendable</tt>
	 *
	 * @throws IOException
	 *             If an I/O error occurs
	 */
	Appendable append(char c) throws IOException;
}
